CompassService
COMPASS Version 6.2, 6.3, 6.4 © General Re Corporation 2021 - 2026. All Rights Reserved (created: 2026-06-16 generated: 2026-07-10)
CompassService - Installation, Configuration & Usage
Introduction
COMPASS 6.2 allows a client application to communicate with the COMPASS engine via REST Services. This COMPASS engine is called CompassService, and offers a similar set of operations as they are known from the COMPASS Server.
The previous version 6.0 of the CompassService also contained the services/endpoints required by the browser-based RuleManager. In 6.2 these endpoints have been split up into CompassService and RuleManagerService: CompassService is Compass' public API (see APIs Overview), while RuleManagerService is the internal API used by RuleManagerApp and not meant for public consumption.
Both CompassService and RuleManagerService are Web applications that need to be deployed in a Servlet Container or can run as a Spring Boot application. They work in a stateless manner, and as such CompassService allows easy deployment and scalability including cloud architectures.
This document describes the installation and configuration of the CompassService.
COMPASS REST API describes the available functions offered by the CompassService.
Prerequisites
The CompassService can be deployed in any Java servlet container that supports at least Servlet API 3.0. We recommend the lightweight Java web server Apache Tomcat.
From version 6.2 onwards CompassService requires Java 11.
Functionality of the CompassService
This document focuses on the services that were in a similar fashion offered by the COMPASS Server. Additional services, like those used by the new RuleManager or CaseViewer, are either no longer part of the CompassService, or are for internal use only.
Most operations offered by the COMPASS Server are supported by CompassService. Those that have been omitted have become useless and therefore deprecated. Should you require a service that is not included, please contact Gen Re COMPASS team. COMPASS REST API describes the currently supported operations.
All services are POST or GET calls. The requests make use of JSON-formatting and can request the response in either JSON or XML format.
The response in XML format is available to support an easy transfer from COMPASS Server to CompassService, as the response keeps its format.
The main supported services are
-
capture and userAction
-
copy, delete, transfer cases or results
-
assessment
-
print application and print result
-
search
Installation
The CompassService distribution consists of the file CompassService.war. This file contains the Web-Application. It can run in a Servlet Container (see Deployment in a Servlet Container) or as a standalone application using Spring Boot (see Standalone Server (Spring Boot)).
Deployment in a Servlet Container
The WAR-file containing the CompassService should be deployed in your Servlet Container (i.e. Tomcat: webapps directory, OpenLiberty: dropins directory). If required restart the Web Server or redeploy the application in the WebServer.
Standalone Server (Spring Boot)
The CompassService.war contains a runnable environment that can be started with the Spring WarLauncher. For quick testing it is possible to start the WebApp without a third-party Servlet Container:
Copy the CompassService.war file to your Compass lib directory.
Run the following command using Java 11:
java -classpath lib\CompassService.war;[databaseDriver] org.springframework.boot.loader.WarLauncher --spring.config.name=CompassServiceThe delivery includes a batch file bin\startRESTService.bat that contains the above Java command and starts the CompassService as a Spring Boot application.
Configuration
The CompassService needs configuration properties which define the environment and the data to work with. Typically these properties are grouped in files, but there are other ways to pass them, too: A comprehensive overview about configuring CompassService with property parameters can be found here.
The main property file is called either CompassService.properties (default file name) or CompassService.yml; in Open Liberty the file needs to be named application.properties. The content of the files are described in detail in CompassService.properties / application properties. Certain properties are like those known from the COMPASS Server/Legacy environment, in particular the file config/server/compass.properties.
We suggest using COMPASS’ ability to use DataSources instead of pure JDBC calls. Therefore, consider creating the appropriate DataSources (see Database / DataSource properties)
Spring Boot
When the CompassService is started as a Spring Boot application with the batch file bin\startRESTService.bat the path to the configuration file is:
config\CompassService.properties
In fact, the file name is defined by the --spring.config.name value in the batch file (see Standalone Server (Spring Boot)) and should be located in the config directory.
Apache Tomcat / Standard Servlet Container
The following instructions describe the standard procedure of a deployment within a Standard Servlet Container. As an example, deployment within Apache Tomcat is explained:
When the CompassService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file CompassService.properties to any location and adapt the environment-entry in CompassService/META-INF/context.xml accordingly.
For example, if the configuration file is located at $CATALINA_HOME/COMPASSConfig/CompassService.properties, the configuration should be as follows:
<?xml version="1.0" encoding="UTF-8"?>
<Context path="/">
<Environment name="spring.config.location"
value="file:../COMPASSConfig/CompassService.properties"
type="java.lang.String"/>
</Context>A sample file CompassService.properties is part of the installation package and will be delivered outside the WAR archive.
Open Liberty / WebSphere
The following instructions describe the procedure of a deployment within an IBM’s Open Liberty. It is also a template for deployment within IBM’s WebSphere. As an example, deployment within Open Liberty is explained:
When CompassService is being deployed under Open Liberty, the file application.properties needs to be placed in $/{server.config.dir} i.e. /opt/wlp/usr/servers/defaultServer.
The default context name of CompassService is CompassService. If this needs to be changed, the WAR archive of CompassService needs to be unpacked and the file WEB-INF/classes/ibm-web-ext.xml needs to be adapted. The context name can be changed by editing the entry context-root:
<web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
version="1.0">
<reload-interval value="0"/>
<context-root uri="/CompassService"/>
<enable-file-serving value="true"/>
<enable-reloading value="true"/>
</web-ext>After editing, the WAR archive needs to be re-packed and can be deployed.
Wildfly / JBoss
If you haven’t done so, deploy your database driver to JBoss / Wildfly and create the Datasources needed for COMPASS (see example below). You can also configure CompassService in such a way that it uses pure JDBC connections (see Installation: Database), however, we strongly recommend to use Datasources when deploying CompassService on JBoss / WildFly.
Since there are multiple options specifying Datasources in JBoss / WildFly, our example below shows one possible way to define the Datasources. We therefore adapt %JBOSS_HOME%/standalone/configuration/standalone.xml. If you want to configure the Datasources in a different way, please consult the documentation of your application server or talk to your database administrator.
<subsystem xmlns="urn:jboss:domain:datasources:6.0">
<datasources>
<datasource jndi-name="java:jboss/COMPASSKnowledge" pool-name="COMPASSKnowledge">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
<validation>
<valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
<validate-on-match>true</validate-on-match>
<background-validation>false</background-validation>
<exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
</validation>
</datasource>
<datasource jndi-name="java:jboss/COMPASSCache" pool-name="COMPASSCache">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
</datasource>
<datasource jndi-name="java:jboss/COMPASSCase" pool-name="COMPASSCase">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
</datasource>
</datasources>
</subsystem>When the CompassService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file CompassService.properties to any location and adapt the environment-entry in the deployment descriptor WEB-INF/web.xml accordingly (reminder: you’ll have to re-package the war archive and re-deploy).
Let’s say the configuration file is in $JBOSS_HOME, the entry would look like
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<env-entry>
<env-entry-name>spring.config.location</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>file:../COMPASSConfig/CompassService.properties</env-entry-value>
</env-entry>
</web-app>In JBoss / WildFly, if running them with default logging configuration, the archive SL4J needs to be excluded from COMPASS' classpath. This has already been configured inside the web app at META-INF/jboss-deployment-structure.xml - so if this needs to be changed again, please adapt said file and re-package the war archive.
<jboss-deployment-structure>
<deployment>
<!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
<exclusions>
<module name="org.slf4j" />
<module name="org.slf4j.impl" />
</exclusions>
</deployment>
</jboss-deployment-structure>CompassService.properties / application properties
Usually, configuration properties are specified in the file CompassService.properties. In Open Liberty (WebSphere) the file application.properties is used instead.
The content of both these files is identical and can be grouped into 4 sections: System properties, Spring Boot related properties, authorization properties and logging properties.
System properties
CompassService stores some information in the property-files mentioned below. These files are:
[compass.server.home]/config/server/compass.properties
[compass.server.home]/config/server/EMConversion.properties
[compass.server.home]/script/*.*
In addition, CompassService needs to know the system-name to work with, and whether data should be preloaded when starting the CompassService.
After modification of any of above-mentioned parameters the web server should be restarted, so the changes take effect.
The following 3 properties are used to configure these:
| Property Name | Description |
|---|---|
compass.server.home |
Location where the 3 above mentioned files/directory are located |
compass.systemname |
Name of the system to be used, and which is defined in compass.properties |
compass.fullloadsystem |
true or false: |
Spring Boot properties
The following properties are used to configure CompassService when started as a plain Spring Boot application.
When deploying in a Servlet Container, these values are typically defined within the Servlet Container and can be omitted in the configuration (file).
| Property Name | Description |
|---|---|
server.port |
REST service is listening on this port [only relevant if the service is running stand-alone] |
server.servlet.contextPath |
REST API prefix [only relevant if service is running stand-alone] |
server.sessionTimeout |
timeout [only relevant if the service is running stand-alone] |
spring.jmx.enabled |
Don’t expose management beans to the JMX domain |
Database / DataSource properties
The following 3 properties allow the definition of Java DataSources for each database connection: knowledge data, case data and cache-table.
Set value to none, if you don’t want to use a DataSource and instead want to use the database configuration in ${compass.server.home}/config/server/compass.properties.
Set values to a JNDI Value, if you want to use DataSources of the servlet container.
For Apache Tomcat, define <ResourceLink> in context.xml and <Resource> in server.xml for each DataSource.
| Property Name | Description |
|---|---|
knowledge.datasource.jndi |
Datasource for knowledge data |
case.datasource.jndi |
Datasource for case / result data |
cache.datasource.jndi |
Datasource for caching table |
Should a property xxxxxx.datasource.jndi be set to none or to an invalid value, a JDBC database connection will be created using the system-properties from the file $\{compass.server.home}/config/server/compass.properties.
When defining a DataSource for a particular connection (to knowledge data, case data or the cache-table), the corresponding connection-properties in the compass.properties-file can be omitted:
For the knowledge data:
[System-name].database.url
[System-name].database.driver
[System-name].database.user
[System-name].database.password
For the cache-table:
[System-name].CacheData.url
[System-name].CacheData.driver
[System-name].CacheData.user
[System-name].CacheData.password
For the case data:
[System-name].CaseData.url
[System-name].CaseData.driver
[System-name].CaseData.password
|
Notice that the user-property can’t be omitted for connection to the case- / result-tables, even when using DataSources. Changes to these tables are marked with the user-ID defined by the property [System-name].CaseData.user |
Cache cleanup properties
COMPASS does not automatically clean up the cache-table by default. The following properties can be used to define a regular cleanup of the cache-table:
| Property Name | Description | Type | default value |
|---|---|---|---|
compass.database.cache.cleanup.cron |
Removing property or setting it to "-" will disable the scheduled task. Please refer to https://docs.spring.io/spring-framework/docs/5.3.20/javadoc-api/org/springframework/scheduling/support/CronSequenceGenerator.html (e.g. "0 0 1 * * *" for running the routine every day at 01:00) |
String |
- |
compass.database.cache.cleanup.hours |
Entries in the c40_cache table older than the amount of hours defined in this property will be deleted |
Integer |
-1 |
compass.database.cache.cleanup.database |
Due to the differences in the SQL query syntax, you need to indicate the which database is being used: |
Integer |
0 |
Authorization properties
This part is only required when the CompassService is used together with the COMPASS Authorization Server (OAuth2). The installation of COMPASS Authorization Server is described in the document Authorization Server 6.2. The corresponding properties are described in the document REST-API-Security
| Property Name | Description | Type | default value |
|---|---|---|---|
compass.security.enabled |
define if security is enabled |
Boolean |
false |
compass.security.cors.enabled |
define if CORS (see https://www.w3.org/wiki/CORS_Enabled) is enabled |
Boolean |
false |
compass.security.cors.crossOrigin.urls |
specify URLs for which CORS is allowed. URLs have to be entered incl. protocol (i.e. http / https) and port. Multiple URLs can be entered as a list separated by comma |
String |
|
compass.security.resource_id |
define the security resource id |
String |
|
compass.security.oauthServerUrl |
define the OAuth server URL for the check_token method |
String |
|
compass.security.clientId |
define the client id for the OAuth server |
String |
|
compass.security.clientSecret |
define the client password (secret) for the OAuth server |
String |
|
compass.security.tokenValidationTimeout |
define the token validation timeout in minutes if security is enabled. |
Integer |
General compass.properties
The following properties define the behaviour of COMPASS in certain situations. These properties are defined in the file compass.properties (see System Properties).
| Property Name | Description |
|---|---|
TURBO |
If set to true, Screenbuilder adds a TURBO button to each screen. If this property is missing, or set to anything but true, no Turbo-button is added to the screen descriptions. |
FORCE_NAVIGATION |
If set to true, Screenbuilder allows the navigation away from a screen (via OK-button or via direct navigation to another screen) even when the current screen is inconsistent. If this property is missing or set to anything but true, navigating away from an inconsistent screen by pressing "OK" or direct navigation is not possible. |
SAVE_BEFORE_QUITTING |
If set to true, screenbuilder will save the case before quitting (i.e. "Cancel"). If this property is missing or set to anything but true, screenbuilder will not save the case when quitting. |
trailing_blanks_fix |
Some databases do not trim trailing spaces as default behaviour. If set to true, the language-parameter is always passed ‘as is’ without trailing spaces. If this property is missing or set to anything but true, language-parameters are passed to the database as 4-characters filled up with spaces. |
GLOBAL_CONSISTENCY |
If set to true, screenbuilder performs a global plausibility check every time an action (an userAction) is sent to the server. If this property is missing or set to anything but true, the check for global consistency is only executed in a few specific situations (i.e.: SAVE, TURBO or clicking OK on the last screen). |
SET_DEFAULT_LOCALE |
If the property is set to true, COMPASS will use the Locale.setDefault-Method. This might be a security concern due to Java safety aspects in certain environments: When this property is missing, or set to anything but true, the method Locale.setDefault(aLocale)will not be called |
HIDE_EMPTY_RELLIST |
If the property is set to true, screenbuilder creates no empty lists for relations. This is the case for the normal list with selected items, but also for other lists in case of a related-question relation: If this property is set to anything but true or missing, all lists of a relation are created on the in the screen description (XML, JSON). |
HIDE_EDIT_BUTTON |
If the property is set to true, screenbuilder creates no EDIT-button for relations: If this property is missing, or set to anything but false, an EDIT-button is created for relations accepting multiple elements. |
UNRELATE_DELETES |
If the property is set to true, screenbuilder does not create a DELETE-button for relate/unrelated relations. Instead, if this CaseObject has no more related questions, the UNRELATE command will delete the CaseObject. If this property is missing, or set to anything but true, both buttons will be displayed, and the UNRELATE command doesn’t delete the CaseObject. |
NAVIGATION_INDENTED |
Screenbuilder 1 only: If set to true, screenbuilder creates a navigation that always includes a submenu for screens that have a relation with subscreens on them.If this property is missing, or set to anything but true, the screenbuilder does not create a submenu for screens that do not contain sub-screens. |
Security related properties
CompassService offers the ability to secure the endpoints captureWithHash / captureWithHashXML with
a hash to protect against URL-tampering. captureWithHash is to be used instead of capture, captureWithHashXML is the secured version of captureXML.
More information about securing these endpoints can be found in CaseViewerApp - Installation: Securing the URL
| Property Name | Description |
|---|---|
compass.security.hash.salt |
A string which will be used to salt the SHA3-256 hash |
compass.security.hash.enabled |
true|false |
Logging
CompassService
In CompassService properties can be configured as a property in the file CompassService.[properties | yaml | json], as JSON-string or property parameter. For a full overview about properties and logging features in CompassService (see Properties Overview of CompassService).
For real-world examples of how to configure CompassService, see How to pass properties.
Profiles
CompassService works with profiles regarding Authorization / Authentication. Depending on the chosen profile, CompassService will either use Spring Authorization (OAuth2) or Keycloak. It is also possible to run CompassService without any Authorization / Authentication.
The type of Authorization / Authentication is selected by specifying the corresponding profile. Profiles have to be defined in the file CompassService.properties or CompassService.yml (see Configuration).
There are 4 profiles available to customize the type of Authorization / Authentication:
| Profile | Explanation |
|---|---|
|
Mandatory for the REST API and Services |
|
Activate the Keycloak Authorization Configuration |
|
Activate Spring Authorization Configuration |
|
Disable authorization, endpoints are not secured |
2 profiles need to be specified - default plus the corresponding Authorization profile.
The profile default always needs to be specified plus either one of the profiles keycloakAuthorization, springAuthorization or noAuthorization .
If not exactly 2 profiles are specified or if the profile default is missing, the application will not start.
| Profiles | Explanation |
|---|---|
|
CompassService with Spring Authorization |
|
CompassService with Keycloak Authorization |
|
CompassService without any authorization |
Integration with Keycloak
In order to run CompassService with Keycloak authentication, the profile keycloakAuthorization has to be activated in the file CompassService.properties or CompassService.yml (see CompassService.properties / application properties). A Customer Keycloak Realm Issuer URI needs to be configured.
| Property Name | Description | Type | default value |
|---|---|---|---|
spring.security.oauth2.resourceserver.jwt.issuer-uri |
In case you want to integrate with Keycloak, specify the URI for the specific Keycloak-realm |
String |
| The issuer uri can be found if you open Keycloak Admin Console, select the corresponding Realm and click Realm Settings. On the right side, you will find the OpenID Endpoint Configuration link. Click the link, it will open a new tab and on the beginning, you will find the issuer uri: |
spring.profiles.active=default,keycloakAuthorization
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/CaseViewerVerifying the installation
After updating the configuration file the installation can be verified.
For both installation types (standalone installation as Spring Boot app or deployment in a servlet container) perform the following steps:
Deployment as stand-alone installation
-
Start the CompassService in stand-alone mode:
Run the batch file bin\startRESTService.bat -
Verify in your console, that the service started:
It reports “Started CompassRESTApp in xxxxx seconds”
Deployment in Servlet Container
Perform the following steps:
-
Start the Servlet Container, or deploy the application
-
Check that the CompassService was deployed correctly (using administration tools of your Web Server)
Test connectivity (for both deployment methods)
-
CompassService has integrated SWAGGER support to describe and document its RESTful API. To view this API documentation open the following URL in your browser:
http(s)://[host]:port/CompassService/api.htmlExample:
http://localhost:8080/CompassService/api.htmlIf CompassService has been installed successfully, your browser should display the SWAGGER representation of CompassService RESTful API:
| A quick overview of CompassService Restful API overview is also available at CompassService REST API. |
Test database connectivity
Run the following REST GET command in a browser, POSTMAN or other tool:
http(s)://[host]:port/CompassService/cspListExample:
http://localhost:8080/CompassService/cspListCheck the response. It should display a list of CSP-Sets (Sets of Company Specific Parameters) which are loaded from COMPASS' database:
